The SCake SDK is a quick and easy way to set up integrations with Project Sugar Cake for making modules and accessing the API.


(_) How To Install (_)

Simply copy the "Mods" folder into the "Content" folder of your devkit / UE5 environment, then load up your usual project. (The assets are uncooked, so they import directly and can be accessed easily)


(_) Usage Instructions (_)

The SDK provides 'dummy' files/assets you point your mod to, then when you export your mod and load it in-game with Project Sugar Cake also installed, the mod will access the SCake API and trigger the appropriate functions/effects. DO NOT include the SDK files with your mod, this will break SCake and the API, I've set up an asset label that should keep it separated, but double check the chunkID to make sure it doesn't conflict with your mod if you use the packaging method!

When importing the SDK, do not change the file path/structure for the ProjectSugarCake folder! The file path must match exactly in order for the API to work properly (also don't change the DataStructure folder at all). The Data Structure folder has internal structure files for SCake required to properly compile certain API functions. Technically, if you don't wish to install the API or have issues with the provided one, you can still create a "dummy actor" in the appropriate folder and re-create the functions/events seen in the SDK to still access the functions properly (Check definitions below for names and variables). Similarly, if there are API functions you're not using you can remove them from your instance of the SDK if you ever find a reason to do so. (This can be useful if an update broke a certain function and the SDK hasn't been updated to fix it yet)

	!!!!!!
(_) Arb Variables and Saving Notes (_)

For memory and file saving weight concerns, stats added at run-time will not persist within the save by default. This is the prefered behavior, however if you have a stat that absolutely MUST persist between saves you can enable the "persist" boolean when registering a stat. However, you need to be extremely careful! If a user disables or uninstalls a module that added an Arb Variable (like ArbString) with persistence checked it will stay in that pal's data and in the save file until it is forcibly removed! To save memory, arb variables that are 0 or none/null are skipped while saving if they are set to only decay (or have no decay) / are a string. This means you can effectively remove an ArbVariable by setting its value to 0/none and it will be removed automatically even if persist is enabled. If, however, you set up a variable with no decay (or set an ArbString with persist) it will remain in memory with no way to clear itself automatically. Try not to cause save bloat with your module and be sparing with what you add, and if you can, do it without persist enabled!


(_) SCake's Structure (_)

While this section isn't required to read, knowing a bit how SCake works internally could help you understand how to effectively pull data and get the references you need. SCake exists as a single Actor within the game-world that is always active, then different modules 'attach' to the main actor as components to then run their own code before they destroy themselves when no longer required.

The Main "ProjectSugarCake" Actor is used to run all of the API and stores any data that needs to persist, this is what you'll refer to when calling API functions.

When an Animation Event starts, an "SCake_EventComp" component is created and attached to the main "ProjectSugarCake" Actor. This EventComp acts as an instance for the Animation Event and stores all data while running the Animation Player, then when the animation event is over the EventComp waits for a short period before destroying itself. If you need to pull any data related to an Animation Event, you'll want to get the EventComp.

Tracking is done in a similar way, when a new Pal is detected an associated "SCake_PalComp" component is created and attached to the main "ProjectSugarCake" Actor. This PalComp stores and runs all the tracking and may even exist when a Pal Character Reference becomes invalid if the character is set to do so, for example, player 'owned' Pals will remain tracking and the data is stored so it can be restored when the Pal becomes valid again. If you want to track tracking data such as current status, you'll want the PalComp.



~!~ API Explaination ~!~

Definitions (What things are called / what they mean)
	SCakeReference / ProjectSugarCake
		This is the reference to the Sugar Cake API and mod itself, you'll need a reference to SCake in-order to use any of the API functions
	
	EventReference / EventComp
		These are references to an instance of the Animation Player. This handles all animation playback and stores data related to that specific event. These are volitile after an animation ends so make sure to pull any needed data before the animation ends (or if pulling from an animation end call, grab and store the data immediately to avoid losing it!)
			- I recommend grabbing whatever data you need before the event ends, then just listen for the end event trigger and compare the reference. This is an effectively 'free' process and avoids issues.
	
	"Pal"
		For our purpose I've just labeled all characters internally as pals, including humans. If something references 'Pal' it means I'm referencing "PalCharacter" which is an internal Palworld class used for pretty much all actors in the game.

Variables (Note " X " before the variable means it is not exposed/editable externally and should only be pulled)
	ProjectSugarCake

		X Pal_Player [Pal Character Reference]
			The local Player Reference (client only)

		X Pal_PlayerController [Pal Player Controller Reference]
			The local Player Controller Reference (client only)

		X SCake_ModVersion [Integer]
			The Internal SCake Mod Version (Generally updated between versions, though I could forget to update it at any point)

		X Data_EventCompArray [SCake_EventComp Reference Array]
			List of all currently active Animation Events

		X System_InputState [SCake_InputState]
			Current InputState for SCake

		X Data_PalsInAnim [TMap Pal Character Reference | SCake_EventComp]
			All Pal Character references currently in an animation event with the associated EventComp

		X Data_PalCompMap [TMap GUID | SCake_PalComp]
			Map of all currently tracked Pal Characters referenced via GUID, used to pull the PalComp which holds all tracked data (Note : When using this to grab Pal References)

		Key_Menu [Key]
			"Menu" Keyboard Keybinding

		Key_Select [Key]
			"Select" Keyboard Keybinding

		Key_Up [Key]
			"Up" Keyboard Keybinding

		Key_Down [Key]
			"Down" Keyboard Keybinding

		Key_Left [Key]
			"Left" Keyboard Keybinding

		Key_Right [Key]
			"Right" Keyboard Keybinding

	SCake_PalComp

		X PalReference [Pal Character Reference]
			The associated Pal Character (This can become invalid, always check validity if you stored the PalComp and try to pull this reference)

		X InstanceID [GUID]
			The InstanceID of this character used to track them between instances/sessions

		X CharacterID [Name]
			The stored CharacterID for this character

		X SexualPleasure [Float]
			Current Sexual Pleasure value (Note this value is to be pulled, not altered directly, if you want to chance the SexualPleasure of a character use the API Function "SCake_Stat_AddPleasure")

		X CloseToOrgasm [Boolean]
			Whether the character has enough Sexual Pleasure to orgasm if triggered

		X SexCount [Integer]
			The total number of times this character has entered an Erotic Animation Event

		X OrgasmCount [Integer]
			The total number of times this character has triggered an orgasm

		X SexHeat [Float]
			The character's current Sex Heat value (effectively arousal)

		X IsAroused [Boolean]
			Whether the character is Aroused, typically set by SexHeat rising high enough

	SCake_EventComp

		X PalList [Pal Character Reference Array]
			Pal Character References in their current Slot Order for the Animation Event (Note the slot order may change through-out an event)

		X EventID [Name]
			The EventID of the currently playing Animation Event

		X AnimID [Name]
			The AnimID of the currently playing Animation

		X NonErotic [Boolean]
			Whether the animation being played is NonErotic or ... not?

		X Aggressors [Pal Character Reference Array]
			Pal Character References currently designated as aggressors

		X AnimRoot [Transform]
			Current root location for the Animation Event

		X PlayAnimDuration [Float]
			Current duration, in seconds, of the current Animation Event

		X PalsHaveOrgasmed [TMap PalReference | Integer]
			How many times each character has orgasmed during the Animation Event, referenced by Pal Character Reference

		X AnimStarted [Boolean]
			Whether the Animation Event has initiated and is ready to set up for animation, only toggles back to false if animation is intentionally interrupted

		X Invalidated [Boolean]
			True if the Animation Event is no longer valid and animation has presumably stopped, used to check if an Animation Event is still running or is awaiting destruction (This can happen either through the animation ending normally or through an error occuring and a forced end being initiated so this isn't useful for error reporting)



Events
	SCake_RegisterAnim
		Call to register an array of animations, invalid data may cause animations not to register
			RegisterAnimData [SCake_RegAnim_Struct]
				Array of animations you'd like to send to the register

	SCake_RegisterAnimEvent
		Call to register an array of animation events, invalid data may cause animation events not to register
			RegisterAnimEventData [SCake_RegAnimEvent_Struct]
				Array of animation events you'd like to send to the register

	SCake_RegisterAllJSON
		(Note : This function runs automatically when the mod loads up so you do not need to call this unless you alter the _LoadList afterward.)
		Registers all .json files in the _LoadList, call when registering new animations through the .json install method.
		
	SCake_SendReportMessage
		Passes a message for SCake to display in the ReportUI
			Message [String]
				Message to display

	SCake_StopAnim_PalTarget
		Stops any animation event the selected pal is involved in
			PalReference [Pal Character Reference]

	SCake_StopAnim_EventRef
		Attempts to stop the specificed Animation Event by reference
			EventReference [EventComp Reference]
		
Functions
	SCake_StartAnimEvent
		Starts an animation event with the defined parameters (params can be passed with nothing and defaults will be used instead, only required value is PalList and setting NonErotic correctly)
			PalList [Pal Character Reference]
				List of characters to include in the animation, can include humans or pals (including players)
			EventID [Name]
				[Optional] Animation Event to play, if is invalid or none is supplied a random compatible animation will be selected to play
			NonErotic [Boolean]
				[Optional] If no EventID is supplied, this determines if the random animation selected should be NonErotic (Overwritten by EventID if valid)
			IncludedTags [Name Array]
				[Optional] Tags to search for when finding animations to play
			RequireAllTags [Boolean]
				[Optional] Whether all tags are required for an animation is compatible, if false then only a single tags is required
			ExcludeTags [Name Array]
				[Optional] Tags that invalidate animations as compatible, excluding them from results
			Aggressors [Pal Character Reference]
				[Optional] Which characters should be considered aggressors
			ActTypes [TMap Pal Character | SCake_ActType]
				[Optional] What Act Type each slot should have in slot order (Must include an entry for every slot or else this is ignored, use "None" if no act type is required for that slot)
			ActLocations [TMap Pal Character | SCake_ActLocation]
				[Optional] What Act Location each character should apply in any point of the event
			AnimRootTransform [Transform]
				[Optional] Location where the animation should play (Can use a character's mesh world transform if desired)
			Returns : ValidStart [Boolean]
				Returns if the animation had valid input and began playing
			Returns : ErrorOutput [Name]
				Returns an output message with any errors
			Returns : PalOrder [Pal Character Array]
				Returns the array of pals passed in the slot order they were sent in for the animation.
			
	SCake_StartAnimEvent_Basic
		Starts an animation with minimal information. If no event ID is supplied (is either "None" or "Random") a random compatible animation will play instead
			PalList [Pal Character Reference]
				List of characters to include in the animation, can include humans or pals (including players)
			EventID [Name]
				[Optional] Animation Event to play, if is invalid or none is supplied a random compatible animation will be selected to play
			NonErotic [Boolean]
				[Optional] If no EventID is supplied, this determines if the random animation selected should be NonErotic (Overwritten by EventID if valid)
			Returns : ValidStart [Boolean]
				Returns if the animation had valid input and began playing
			Returns : ErrorOutput [Name]
				Returns an output message with any errors
			Returns : PalOrder [Pal Character Array]
				Returns the array of pals passed in the slot order they were sent in for the animation.

	SCake_Stat_AddPleasure
		Adds Sexual Pleasure to the referenced character
				PalReference [Pal Character Reference]
					Character to add Sexual Pleasure to
				AmountToAdd [Float]
					Amount of Sexual Pleasure to add
				Returns : PleasureOutput [Float]
					The new amount of Sexual Pleasure the referenced character

	SCake_CheckStat_Pleasure
		Returns the current Sexual Pleasure of the referenced character
			PalToCheck [Pal Character Reference]
				Which character to check the Sexual Pleasure of
			Returns: SexualPleasure [Float]
				The Sexual Pleasure of the checked character

	SCake_GetPalAnim
		Checks if the given character is in an animation and if so returns the Event Reference
			PalReference [Pal Character Reference]
				Pal Character reference to search through the playering Animation Event List for
			Returns : InAnimation [Boolean]
				Whether the character was found in the playing Animation Event List
			Returns : EventReference [EventComp Reference]
				If InAnimation was true, returns the EventComp Reference

	SCake_InterpretError
		Takes the Name variable from an error and translates it into a human readable string for use in either UI elements or easier debugging
			ErrorInput [Name]
				The raw error name variable from SCake
			Returns : ReadableOutput [String]
				Readable string ready for use

	SCake_AdjustAnimCamPos
		Adjusts the player camera position while in animations (Starts off the saved position then offsets by the input amount)
			AdjustPos [Vector]
				Ammount to offet the camera to compared to the saved position
			SavePos [Boolean]
				Whether the new position should be saved or just adjust this once
			Returns : FinalPos [Vector]
				Offset after adding the AdjustPos amount

	SCake_TraceForPal
		Uses a line-trace to search for pals, useful to target and apply code to pals the player is looking at. (Uses the camera position and rotation, not all pals are able to be detected this way so this is mostly for debug purposes)
			Distance [Integer]
				Distance from the camera to check in UE units
			Returns : Valid [Boolean]
				Whether the trace found a valid pal
			Returns : PalFound [Pal Character]
				Pal Reference the trace found

	SCake_TrackReturnAll
		Returns referneces for all valid pals currently being tracked by SCake (Useful if you need to grab references when starting up your module and/or need to apply/check status)
			Returns: PalsTracked [Pal Character Reference Array]

	SCake_CheckStat_SexHeat
		Returns the Pal Reference's associated Sex Heat value along with if they have enough to currently be aroused
			PalReference [Pal Character Reference]
			Returns : SexHeat [Float]
				Current Sexual Heat value, typically seen as a percentage with 100 having '100%' of Heat's effect
			Returns : IsAroused [Boolean]
				Whether the current Heat value is above the character's arousal threshold

	SCake_Stat_AddSexHeat
		Adds the given amount to the specified characters's Sexual Heat status and returns the new value along with if the character has enough Heat to be aroused
			PalReference [Pal Character Reference]
				Character to add Sexual Heat to
			AmountToAdd [Float]
				Amount to add to the Sexual Heat stat
			Returns : SexHeat [Float]
				New Sexual Heat stat of the given character
			Returns : IsAroused [Boolean]
				Whether the new value has the character's Sexual Heat high enough to be aroused

	SCake_Stat_ArbChangeString
		Either Adds or Changes the Arbitrary String by Name for the designated character (Used to store additional stats for modules)
			PalReference [Pal Character Reference]
				Character to add/change the value for
			ArbName [Name]
				Name to give the string, using the same name as a registered string to change the value
			ArbString [String]
				String to set the value to
			Persist [Boolean]
				Whether this value should persist within the save data or not

	SCake_CheckStat_ArbString
		Returns the ArbString if one is defined for the designated character, if none is defined then none will be returned
			PalRefernce [Pal Character Reference]
				The character to get the stat from
			ArbName [Name]
				Name the ArbString is registered under
			Returns : ArbString [String]
				String value for the given ArbName
			Returns : Persists [Boolean]
				Whether this ArbVariable is set to persist or not

	SCake_ValidForAnim
		Returns if the character is valid to start an animation or not without scanning for animations to play or starting an animation event (NOTE : Validity is already checked when calling for an animation to start so you only need to run this if you need the return value before starting an animation event)
			PalReference [Pal Character Reference]
				Character to check if valid to start animations
			Returns : IsValid [Boolean]
				If true, the character is available to start an animation with
			Returns : ErrorOutput [Name]
				If not valid then this returns the raw error output

	SCake_GetCompatEvents
		Returns the EventID for compatible Animation Events with the passed parameters, the return order is random. Useful if you need to get potential animations before actually starting an animation, or to check if a set of character can even start an animation in the first place (Combine this the start animation calls)
			PalList [Pal Character Array]
				Characters to include in the animation
			FindMaxCount [Integer]
				How many animations to find before returning results, if value is higher than 0 then random Events will be returned until the max number is reached (0 will return all possible events, if you just need a random EventID to playback and don't need to do filtering or caching, you can set this value to 1 to get a random compatible Animation Event)
			NonErotic [Boolean]
				Whether an Animation Event should be NonErotic to be included in the return results
			IncludeTags [Name Array]
				Tags an Animation Event must include at least one of to be included in the return results
			RequireAllTags [Boolean]
				Whether all IncludedTags should be required for an Animation Event to be included in the return results
			ExcludeTags [Name Array]
				Tags to exclude from the return results
			Aggressors [Pal Character Array]
				Which characters must be considered aggressors, will still return aggressive results if set sent as an empty array since this only ensures the given character is an aggressor but does not prevent characters from being aggressors
			ActTypes [TMap Pal Character | SCake_ActType]
				ActTypes to limit search to, where the associated character is in a specific ActType at any point in the Event
			ActLocations [TMap Pal Character | SCake_ActLocation]
				ActLocation to limit search to, where the associated character in in a specific ActLocation at any point in the Event
			Returns : EventIDList [Name Array]

	SCake_GetPalComp
		Returns the PalComp associated with the referenced Pal Character (PalComp stores the currently tracked stats for the given pal, note that PalComp objects are volitile and can invalidated! They will delete when no-longer needed so always check if they are valid before trying to pull data or else you may cause a crash!)
			PalReference [Pal Character Reference]
				Pal Character you want the associated PalComp for
			Returns : Valid [Boolean]
				Whether a PalComp was found in the stored tracker map (Data_PalCompMap)
			Returns : PalComp [SCake_PalComp Reference]
				The associated SCake_PalComp you can use to pull data from

Dispatchers
	SCake_ED_AnimStart
		Called whenever an Animation Event starts and returns a reference to it (Store this value if you need to reference it later, use the API call 'SCake_GetEventCompParams' to pull data from the event, store it if needed)
			Returns : EventReference [EventComp Reference]
			Returns : PalList [Pal Character Reference Array]
				List of characters in the animation in their slot order

	SCake_ED_AnimEnd
		Called whenever an Animation Event starts and returns a refernece to it (It's recommended to pull data immediately using 'SCake_GetEventCompParams' if needed as EventReferences become volitile after an Animation Event Ends, I recommend mostly using this reference to compare to stored references from other API calls)
			Returns : EventReference [EventComp Reference]
			Returns : PalList [Pal Character Reference Array]
				List of characters in the animation in their slot order

	SCake_ED_EventOrgasm
		Called whenever an Animation Event triggers climax
			Returns : EventReference [EventComp Reference]
				Reference to the specific event
			Returns : PalsOrgasmed [Pal Character Reference Array]
				Characters who orgasmed in the event
			
	SCake_ED_PalOrgasm
		Called from individual pals who orgasm
			Returns : PalReference [Pal Character Reference]
				The pal who orgasmed

	SCake_ED_PalAroused
		Called when a pal reaches enough Heat to enter an aroused state
			Returns : PalReference [Pal Character Reference]

	SCake_ED_TrackPalEnabled
		Called when a pal becomes active in the tracker
			Returns : PalReference [Pal Character Reference]

	SCake_ED_TrackPalDisabled
		Called when a pal becomes inactive in the tracker (Note : Pals do not instantly start tracking or instantly stop tracking when they become valid/invalid, do not use this for validity checks! Use 'IsValid' through UE natively instead!)
			Returns : PalReference [Pal Character Reference]